<h1>Event Handling</h1>

<p>Skeleton Framework includes a library for managing events and event listeners/handlers.  The interface is very simple, and very flexible.  Here is an example.</p>

<pre class="prettyprint lang-php">
&lt;?php

function callbackFunction() {
	echo 'Callback function called!';
}

$manager = new A_Event_Manager();

$manager->addEventListener('event1', 'callbackFunction');

$manager->fireEvent('event1');

// outputs "Callback function called!"

?&gt;
</pre>

<h2>Handling Events With Callback Functions</h2>

<p>A_Event_Manager::addEventListener can accept all types of callbacks.  This includes:</p>

<ul>
	<li>String callbacks</li>
	<li>Array callbacks</li>
	<li>create_function()</li>
	<li>Closure (anonymous functions, requires PHP 5.3+)</li>
</ul>

<p>Here is a very useful example of an array callback.</p>

<pre class="prettyprint lang-php">
&lt;?php

class MyEventHandler {
	public function handleEvent1($eventName, $eventObject) {
		echo 'This event has been fired: ' . $eventName;
	}
}

$manager = new A_Event_Manager();

$listener = new MyEventHandler();
$manager->addEventListener('event1', array($listener, 'handleEvent1'));

$manager->fireEvent('event1');

// outputs "This event has been fired: event1"

</pre>

<h2>Handling Events With Listener Objects</h2>

<p>The Event library also allows you to pass implementations of A_Event_Listener as the listener also.</p>

<pre class="prettyprint lang-php">
&lt;?php

class MyEventHandler implements A_Event_Listener {
	public function onEvent($eventName, $eventObject) {
		echo 'This event has been called: ' . $eventName;
	}
}

$manager = new A_Event_Manager();

$listener = new MyEventHandler();
$manager->addEventListener('event1', $listener);

$manager->fireEvent('event1');

// outputs "This event has been fired: event1"

?&gt;
</pre>

<p>Alternatively, the class itself can define what event(s) it should be attached to.</p>

<pre class="prettyprint lang-php">
&lt;?php

class MyEventHandler implements A_Event_Listener {
	public function onEvent($eventName, $eventObject) {
		echo 'This event has been called: ' . $eventName;
	}
	public function getEvents() {
		return 'event1';
	}
}

$manager = new A_Event_Manager();

$listener = new MyEventHandler();
$manager->addEventListener($listener);

$manager->fireEvent('event1');

// outputs "This event has been fired: event1"

?&gt;
</pre>

<h2>Associating One Handler to Multiple Events</h2>

<p>Several events can be given one handler by giving an array of events, instead of one.</p>

<pre class="prettyprint lang-php">
&lt;?php

function callbackFunction($eventName, $eventObject) {
	echo 'Callback function called: ' . $eventName;
}

$manager = new A_Event_Manager();

$manager->addEventListener(array('event1', 'event2'), 'callbackFunction');

$manager->fireEvent('event1');

// outputs "Callback function called: event1"

$manager->fireEvent('event2');

// outputs "Callback function called: event2"

?&gt;
</pre>

<p>The same can be done with implementations of A_Event_Listener.</p>

<pre class="prettyprint lang-php">
class MyEventHandler implements A_Event_Listener {
	// ...
	
	public function getEvents() {
		return array('event1', 'event2');
	}
}
</pre>

<h2>Removing Events/Handlers</h2>

<p>A_Event_Manager provides two methods: one for removing events, and one for removing handlers.  When an event is removed, all handlers associated with it are also removed.  Here is the usage of removeEventListener().<p>

<pre class="prettyprint lang-php">
&lt;?php

function callbackFunction($eventName, $eventObject) {
	echo 'Callback function called: ' . $eventName;
}

$manager = new A_Event_Manager();

$listener = 'callbackFunction';
$manager->addEventListener('event1', $listener);
$manager->removeEventListener($listener);

?&gt;
</pre>

<p>And this demonstrates the removal of an entire event.</p>

<pre class="prettyprint lang-php">
&lt;?php

function callbackFunction($eventName, $eventObject) {
	echo 'Callback function called: ' . $eventName;
}

$manager = new A_Event_Manager();

$manager->addEventListener('event1', 'callbackFunction');
$manager->killEvent('event1');

?&gt;
</pre>

<h2>Handling Exceptions</h2>

<p>A_Event_Manager also lets you define the class of exception to use when it encounters a problem (non-existant event, invalid listener, etc.).  There are two ways to define it: in the constructor, and setException().</p>

<pre class="prettyprint lang-php">
&lt;?php

// in the constructor:
$manager = new A_Event_Manager('Exception');

// or with setException:
$manager->setException('Exception');

// or to reset to the default:
$manager->setException(true);

?&gt;
</pre>
